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Chapter  1  -  About  This  Manual 


Chapter  1  About  This  Manual 

1.1  Purpose 

The  purpose  of  this  manual  is  to  describe  the  features  of  the  Intermetrics'  SAMeDL  Development 
Environment  (SDE)  for  the  Informix  Database  Management  System  on  the  386PC  platform  with 
Interactive  Ul^  and  Alsys  Ada.  The  language  supported  is  defined  in  Ae  SAMeDL  Language 
Reference  Manual  [LRM].  This  user's  manual  is  not  intended  to  be  a  language  tutorial  for 
SAMeDL.  In  addition,  it  is  assumed  that  you  have  an  underlying  working  knowledge  of 
Informix  [Informix]  and  the  Ada  standard  [Ada]. 

1.2  Organization 

The  organization  of  this  document  is  as  follows: 

•  Chapter  2,  SDE  Overview,  briefly  describes  the  SDE  components,  what  each 
component  is  used  for,  and  how  the  components  relate  to  each  other. 

•  Chapter  3,  SDE  Library  File  System,  contains  an  overview  of  libraries  and  how  SDE 
uses  them. 

•  Chapter  4,  Getting  Started  With  SDE,  demonstrates  a  simple  scenario,  providing 
enough  information  for  users  to  get  started  developing  Ada/SQL  interfaces  with 
SAMeDL. 

•  Chapter  5,  Building  AdafSQL  Interfaces  With  SAMeDL,  provides  detailed  information 
on  how  to  generate  Ada/SQL  interfaces  using  the  SAMeDL  compiler,  and  also  outlines 
the  procedures  that  should  be  followed  for  including  generated  interfaces  in  an  Ada 
application  program. 

•  Chapter  6,  Implementation  Dependent  Features,  discusses  SAMeDL  features  which  are 
dependent  on  the  Informix  DBMS  implementation. 

•  Chapter  7,  Tool  Limitations,  outlines  general  restrictions  and  tool  limitations  imposed 
by  the  current  release  of  the  SAMeDL  Development  Environment  for 
Infonnix/386PC/Interactive  UNIX/Alsys. 

•  Chapter  8,  SDE  Command  Reference  Marmal  Pages,  contains  a  detailed  reference  for 
each  command  in  SDE. 
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13  Syntax  Conventions 

The  following  explains  the  notational  conventions  used  in  SDE  command  syntax  throughout  this 
document; 

jQTz  Items  expressed  in  lower-case  italic  letters  are  used  to  represent  user- 
supplied  names.  You  should  substitute  an  appropriate  value.  For  exan^le, 

pathname 

would  mean  that  you  should  specify  the  text  that  represents  a  file  or 
directory  pathname. 

[  ]  Brackets  are  used  to  denote  items  that  are  optional.  For  example, 

sde.cleanlib  [pathn^une] 

means  that  you  may  specify  the  command  with  or  without  supplying  a 
pathname. 


An  ellipsis  indicates  that  you  may  optionally  repeat  the  preceding  item  one 
or  more  times.  For  example, 

module_name  ... 

means  that  a  series  of  module  names  can  follow  the  one  listed. 

Unless  otherwise  noted,  you  may  specify  options  on  a  SDE  command  in  any  order.  Also,  option 
keywords  are  not  case  sensitive  and  may  be  truncated  as  long  as  the  resulting  abbreviation  is 
unambiguous.  For  example,  the  following  two  commands  are  equivalent; 

sde.ls  -1  niy_library  -v  iny_def_inodul« 

sde.ls  -Verbose  -Library  iry_library  ny_def.jnodule 


1.4  References 

[Ada]  R^erence  Manual  for  the  Ada  Programming  Language,  Ada  Joint  Program 
Office,  1983. 

[AdaRef]  FirstAda  Ada  Software  Engineering  Environment:  Application  Developer’s 
Guide  and  Appendix  F  version  4.4,  Alsys,  Inc,  1990. 

[Informix]  Informix-OnLine  Administrator’s  Guide,  Informix  Software,  Inc.,  1990. 
Part  No.  000-7051. 

[InfESQL]  Irrformix-ESQUC  Programmer’s  Manual,  Informix  Software,  Inc.,  1990. 
Part  No.  000-7053. 
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[LRM]  SAMeDL  Language  Reference  Manual,  Intcrmctiics,  Inc.,  IR-VA-011-1,  07 
July  1992. 

[SAMEGuide]  Guidelines  for  the  Use  of  the  SAME,  Marc  Graham:  Software 
Engineering  Institute/Camegie  Mellon  University,  Technical  Report  CMU/SEI-89-TR- 
16.  May  1989. 

[SDElnst]  SAMeDL  Development  Environment  Installation  Guide,  Intermetrics,  Inc., 
IR-VA-026-2, 01  September  1992. 
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Chapter  2  SDE  Overview 

The  SAMeDL  Development  Environment  (SDE)  provides  you  with  a  software  environment  for 
developing  Ada/SQL  interfaces  through  the  use  of  SAMeDL.  The  SDE  toolset  consists  of  a 
compiler,  which  processes  SAMeDL  source  files  to  generate  Ada/SQL  interfaces,  and  the 
Module  Manager,  which  assists  you  with  SDE  library  management  and  other  facets  of  interface 
development 

The  SDE  toolset  includes  the  following: 


samedi 

sde.cleanlib 

sde.creatar 

sde.creatlib 

sde.ls 

sde.inkscript 

sde.purge 

sde.rm 

sde.rinlib 


invoke  the  SAMeDL  compiler 
reinitialize  an  SDE  library 

create  a  library  archive  file  for  compiled  concrete  modules 

create  an  SDE  library 

list  compiled  SAMeDL  modules 

generate  an  Ada  compilation  script  file  for  an  interface  file 
remove  out  of  date  files  from  an  SDE  libra^ 
remove  a  SAMeDL  module  from  an  SDE  library 
remove  an  SDE  library 


2.1  The  SDE  SAMeDL  Compiler 

The  SAMeDL  compiler  processes  SAMeDL  source  files  and  generates  interface  files 
representing  the  prescribed  Ada/SQL  interface. 

Like  an  Ada  compiler  which  deals  with  compilation  units,  the  SAMeDL  compiler  works  with 
modules,  which  are  the  smallest  pieces  of  code  that  can  be  successfully  compiled  and  shared.  A 
SAMeDL  source  file  may  consist  of  one  or  more  modules. 

In  SAMeDL,  there  are  three  types  of  modules.  A  module  may  be  either  a  definitional  module 
containing  shared  defmitions,  a  schema  module  containing  table,  view,  and  privilege  definitions, 
or  an  abstract  module  containing  local  definitions  and  procedure/cursor  declarations. 

The  SAMeDL  compiler  will  generate  interface  files  for  each  definition  module  (in  the  form  of  an 
Ada  package  specification/body  pair)  and  each  abstract  module  (in  the  form  of  a  layered 
interface  consisting  of  an  Ada  package  specification/body  pair  and  an  object  code  file  generated 
from  a  C  with  embedded  SQL  file).  No  interface  files  are  generated  for  schema  modules.  The 
generated  interface  files  collectively  represent  the  Ada/SQL  interface  you  would  use  in  your  Ada 
application  program. 

SAMeDL  is  analogous  to  Ada  in  that  it  also  has  the  concept  of  separate  compilation.  SAMeDL 
modules  may  use  (through  the  use  of  context  clauses)  information  contain^  in  other  modules 
that  you  have  previously  compiled.  All  separate  compilation  information  is  kept  in  ordinary  host 
file  system  directories  and  files.  These  files/directories  along  with  any  generated  interface  files 
are  organized  into  an  SDE  library,  which  again  is  somewhat  similar  to  the  development  library 
concept  used  by  most  Ada  development  systems. 

As  in  the  case  of  most  language  compilers,  the  SAMeDL  compiler  will  perform  the  appropriate 
syntactic  and  semantic  error  checking.  All  error  messages  are  reported  to  the  standa^  output 
device.  You  may  also  optionally  specify  that  a  source  listing  file  be  generated  in  which  case,  if 
you  had  any  errors,  the  errors  would  be  interleaved  with  the  SAMeDL  source  code  in  your 
listing. 
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2.2  The  SDE  Module  Manager 

The  SDE  Module  Manager  is  a  set  of  tools  which  you  may  use  to  assist  with  SDE  library 
management  and  other  facets  of  interface  development  These  tools  include  sde.cleanlib, 
sde.creatar,  sde.creaUib,  sdeJs,  sde.inkscript,  sde.purge,  sde.nn,  and  sde.niilib. 

sde.cleanlib 

sde.cleaniib  will  allow  you  to  empty  an  existing  SDE  library  of  ail  compilation  information. 
The  command  will  re-initialize  the  names.dbe  and  samedl.dat  files  and  remove  the  remaining 
contents  of  the  samedl.lib  subdirectory. 

sde.creatar 

sde.creatar  is  useful  ^cr  creating  and  updating  a  library  archive  file  that  contains  the  object  code 
files  generated  from  the  C  with  embedded  SQL  for  abstract  modules.  The  object  code  files  can 
then  more  easily  be  included  as  part  of  the  Ada  link  step  for  the  application  program  (as  opposed 
to  specifying  each  of  the  object  code  files  individually  in  the  link  step). 

sde.creatlib 

sde.creatlib  is  used  to  create  and  initialize  a  new  SDE  library.  It  creates  a  directory  named 
samedl.lib  in  the  library  directory,  and  creates  the  files  samedl.dat  and  names.dbe  in  the 
samedl.lib  directory. 

sde.ls 

sde.ls  provides  you  with  a  list  of  the  SAMeDL  modules  compiled  in  an  SDE  library.  Useful  is 
the  interface  option  which  will  provide  information  concerning  the  interface  files  generated  for  a 
module. 

sde.mkscript 

sde.mkscript  will  create  a  template  for  performing  the  Ada  compilation  of  the  generated  Ada 
interface  tiles  (and  the  units  they  depend  on)  for  the  definitional  or  abstract  modules. 

sde.purge 

sde.  purge  will  remove  all  out  of  date/unused  tiles  from  an  SDE  library.  These  files  include 
temporary  tiles  (e.g.,  those  used  during  compilation)  or  interface  tiles  that  have  been  put  out  of 
date  due  to  recompilation  of  the  associated  SAMeDL  modules.  In  addition,  sde.purge  will  also 
remove  the  library  state  information  backup  tile  samedLdaLback. 

sde.rin 

sde.rm  allows  you  to  remove  all  information  and  related  interface  files  associated  with  modules 
compiled  in  the  SDE  library. 

sde.rinlib 

You  use  sde.niilib  to  remove  an  SDE  library  and  aU  of  the  information  it  contains. 
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Chapter  3  SDE  Library  File  System 

This  chaptn  contains  an  overview  of  SDE  libraries  and  the  files  that  comprise  them. 

3.1  Overview  Of  SDE  Libraries 

An  SDE  library  is  a  host  file  system  directory  which  acts  as  a  central  database  of  SAMeDL 
compilation  information  and  related  generated  interfaces. 


Figure  3.1:  Contoits  of  an  SDE  Library 

Every  directory  representing  an  SDE  library  will  contain  the  directory  samedUlib.  samedlJib  in 
turn  contains  the  fUes  names.dbe,  samedLdat,  and  samedl.dat.back,  and  various  files  ending 
with  .sme,  .ec,  .o,  and  .a  extensions.  In  addition,  there  are  a  variety  of  tempor:^  files  that  may 
appear  under  samedl.lib:  samedl.lock,  samedl.tmp,  and  files  ending  with  .c  and  .com 
extensions. 

Note:  in  general,  it  is  not  advisable  for  you  to  modify  or  place  any  files  in  the  director 
samedLlib  that  are  not  otherwise  generated  by  SDE.  In  particular,  sde.riiilib  and  sde.cleanlib 
do  die  equivalent  of  a  UNDC  "rm  -r  samedLlib”  as  part  of  their  operation. 


Intermetrics,  Inc. 


7 


SAMeDL  Development  Environment  -  User  Manual 


3^  Core  Library  Files 

When  you  initially  create  a  new  SDE  library  (via  sde.creatlib)  or  "clean”  an  existing  SDE  library 
(via  sde.cleanlib),  the  directory  samedLiib  will  only  contain  the  following  core  library  files: 
samedl.dat  and  names.dbe.  In  certain  circumstances,  a  backup  file  for  samedl.dat  named 
sainedl.dat.back  will  also  be  present. 

samedl.dat 

samedl.dat  is  the  net  disk  data  file  for  the  library.  It  contains  a  series  of  records,  each  record 
containing  the  data  for  a  single  node  in  the  internal  representation  of  the  dependency  tree.  The 
information  in  the  file  is  in  text  format,  that  can  be  read/written  by  the  SDE  module  manager  and 
the  SAMeDL  compiler. 

The  internal  representation  of  the  dependency  information  is  tree-like.  Each  node  in  the  tree 
represents  a  file  in  the  SAMeDL  system,  and  has  information  about  all  nodes  that  are  dependent 
on  it  and  nodes  that  it  depends  on  (called  CaredAboutBy  and  CaresAbout  arcs  respectively). 
Each  node  also  contains  the  time  it  was  created,  the  external  source  file  it  was  created  from,  the 
name  of  the  source  file  saved  in  the  library  and  the  name  of  the  library  file  that  the  generated 
code  resides  in. 

Nodes  are  given  node  numbers  that  uniquely  identify  them.  This  practice  facilitates  saving  the 
tree  to  the  designated  disk  file  and  reading  it  back  because  pointers  do  not  need  to  be  included  in 
the  disk  file.  It  also  facilitates  the  use  of  uniform  data  structures  for  the  internal  representation 
because  variable  length  records  do  not  need  to  be  used.  Instead,  lists  are  maintained  off  each 
node  that  contain  the  node  numbo'S  of  the  nodes  that  the  node  depends  upon,  or  is  depended 
upon  by. 

The  records  in  the  disk  data  have  the  following  fields; 

Node  Number  number  of  the  node  that  specifies  the  unit 

Node  Type  the  type  of  file  this  node  points  to 

Unit  Name  name  of  the  compiled  unit 

Time  Entered  time  the  unit  was  entered  into  the  library 

Library  File  name  of  file  saved  in  library 

External  File  pathname  of  file  that  the  node  was  generated  fi’om 

Cares  About  Arc  Num  number  of  cares  about  arcs  from  this  node 

Cares  About  Arc  List  list  of  cares  about  arcs  from  this  node 

Cared  About  By  Arc  Num  number  of  care  about  arcs  to  this  node 

Cared  About  By  Arc  List  list  of  care  about  arcs  to  this  node 

The  records  in  the  disk  data  file  are  written  out  in  text  form,  one  after  the  other  with  a  special 
character  separating  each  node. 
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samedl.datback 

The  samedl.dat.back  file  is  a  backup  copy  of  the  samedl.dat  file  that  the  SAMeDL  compiler 
and  the  sde.rm  command  make  before  they  change  the  samedl.dat  file,  samedl.dat.back  will 
contain  the  prior  library  state  information  and  thus  will  allow  you  to  undo  the  effects  of  the  last 
samedi  or  sde.rm  conunand  (provided  that  a  sde.purge  conunand  has  not  been  since  executed; 
see  below).  In  order  to  restore  the  library  back  to  its  prior  state,  you  should  go  to  the  samedl.lib 
directory  corresponding  to  your  SDE  library,  remove  the  existing  samedl.dat  file,  and  rename 
(using  the  UNIX  mv  conunand  for  example)  samedl.datback  to  samedl.dat.  Note  that  because 
of  the  semantics  of  the  sde.purge  command,  an  SDE  library  may  not  be  restored  if  the  library 
has  been  purged. 

names.dbe 

The  names.dbe  file  is  a  text  file  that  maintains  two  integer  counters  used  internally  by  the 
compiler  to  keep  track  of  procedures  and  variables  across  separate  compilations. 
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33  Modules  and  Interface  Files 

When  a  SAMeDL  module  is  compiled  into  an  SDE  library,  depending  on  the  type  of  module,  die 
comr;ler  will  generate  a  series  of  files  in  the  samedLlib  directory.  These  are  as  foUows: 


File  Name 

Description 

Definitional  Module 

D_xxxxx.sme 

Text  file  containing  SAMeDL  source  code 
representing  the  definitional  module 

P_xxxxx_.a 

Generated  Ada  package  specification  file 

B_xxxxx.a 

Generated  Ada  package  body  file 

Schema  Module 

S_xxxxx.smc 

Text  file  containing  SAMeDL  source  code 
representing  the  schema  module 

Abstract  Module 

A_xxxxx.sme 

Text  file  containing  SAMeDL  source  code 
representing  the  abstraa  module 

P_xxxxx_.a 

Generated  Ada  package  specification  file 

B_xxxxx.a 

Generated  Ada  package  body  file 

E_xxxxx.ec 

Generated  C  w/  embedded  SQL  (C/ESQL) 
file 

E_xxxxx.o 

Object  code  for  the  expanded/compiled 
C/ESQL  file 

who-e  xxxxx  denotes  a  unique  integer. 


3.4  Miscellaneous  Temporary  Files 

Occasionally  during  the  normal  operation  of  running  the  SAMeDL  compiler  and  the  Module 
Manager  utUity  tools,  temporary  ^es  may  be  generated  in  the  samedLlib  directory.  A  brief 
explanation  of  these  files  follow. 

samedLlock 

This  file  is  present  if  someone  is  currently  operating  in  the  SDE  library  and  therefore  has  it 
locked.  If  you  attempt  to  operate  within  the  library  and  it  is  already  locked,  you  will  be  notified 
by  an  appropriate  informative  message  and  the  operation  will  be  terminated. 

Occasionally  you  will  be  notified  that  the  library  is  locked  even  though,  in  reality,  nobody  is 
currendy  using  the  library.  Hus  would  typically  occur  if  you  abnormally  terminate  the  conqiiler 
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or  an  SDE  command  causing  the  lock  file  to  not  be  coirectly  removed  (and  thereby  preventing 
yourself  and  others  from  using  the  library).  If  you  are  sure  this  is  the  case,  you  can  correct  the 
problem  easily  by  removing  samedlJock  from  the  library's  samedMib  directory. 

samedLtmp 

This  file  is  a  temporary  text  file  used  by  the  compiler  during  the  update  of  an  SDE  library. 

.c  Files 

Files  whose  names  take  the  form  E_xxxxxx  are  files  which  contain  the  expanded  C  source  code 
output  of  the  C/ESQL  precompiler."  It  is  this  file  that  is  compiled  (transparent  to  the  user  by  the 
SAMeDL  compiler)  by  the  C  compiler  to  produce  the  .o  files,  xxxxx  (see  above)  is  a  unique 
integer  and  will  have  the  same  value  as  the  corresponding  E_xxxxx.ec  file. 

.com  Files 

Files  whose  names  take  the  form  xyz.coin  are  UNIX  command  (or  script)  files  written  in  the 
UNIX  C-shell  (csh)  language.  TUs  conunand  file  is  generated  and  us^  by  the  SAMeDL 
compiler  to  (transparently)  precompile  the  .ec  files  and  C  compile  the  .c  files  associated  with 
every  abstract  module  in  Ae  SAMeDL  input  source  file  xyz.sme. 

3.5  Standard  SAMeDL  Modules  and  Ada  Support  Packages 

As  documented  in  [LRM]  Appendices  A,  B,  and  C,  there  are  a  number  of  standard  SAMeDL 
modules  and  Ada  support  packages  defined  as  part  of  SAMeDL.  These  include  the  following; 

•  The  SAMeDL  modules  SAMeDL_Standard  and  SAMeDL_Systeni 

•  The  Ada  packages  SQL_Standard,  SQL  Database_Error  Pkg,  SQL  Bo(riean_Pkg, 

SQL_Int_Pkg,  SQL  Sihallint_Pkg,  SQL  Real_Pkg,  SQC_Double_Precision“Pkg, 
SQL_Char_Pkg,  an(rSQL_EnuiiieratiwiJPkg.  ~  "  " 

The  standard  SAMeDL  modules  contain  predefined  elements  such  as  predefined  base  domain 
declarations  and  database  specific  constants.  These  modules  may  be  us(^  in  SAMeDL  code  you 
develop  just  as  you  would  any  other  SAMeDL  module  by  bringing  them  into  context  through  the 
use  of  context  clauses  .  Note  however  that  before  you  can  use  these  modules,  they  must  have 
been  previously  compiled  by  the  SAMeDL  compiler  into  your  SAMeDL  library.  This  is 
discussed  further  in  Section  5.2  of  this  document 

Because  the  interfaces  generated  by  the  SAMeDL  compiler  depend  on  the  standard  Ada  support 
packages,  you  must  compile  the  standard  packages  into  an  Ada  development  library  that  can  be 
used  by  your  interfaces  and  application  programs.  For  further  information  on  how  to  accomplish 
this,  please  refer  to  Section  5.3. 
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Chapter  4  Getting  Started  With  SDE 

This  chapter  presents  some  basic  scenarios  for  using  the  SAMeDL  Development  Environment: 
creating  an  SDE  library,  compiling  a  SAMeDL  source  file,  and  creating  an  Ada  application 
program  which  uses  the  SAMeDL  compiler  generated  modules  to  interface  with  the  database 
environment  The  scenarios  have  intentionaUy  been  kept  simple;  details  are  deferred  to  later 
sections  of  this  manual. 

Suppose  you  want  to  design  an  Ada  application  program  which  interacts  with  a  database 
environment  The  basic  steps  are: 

1.  Create  the  Informix  Database  that  the  application  wDl  access,  if  it  does  not  already 
exist 

2.  Create  an  SDE  library  for  the  database. 

3.  Prepare  a  SAMeDL  source  input  Ele  and  compile  it  into  the  SDE  library. 

4.  Write  the  Ada  application  program  which  uses  the  SAMeDL  standard  packages  and  the 
Ada  definition/abstract  modules  generated  by  the  SAMeDL  compiler. 

5.  Compile  and  link  the  Ada  application  program. 

4.1  Creating  A  Database 

The  initial  creation  and  maintenance  of  a  Informix  database  is  beyond  the  scope  of  SAMeDL. 
As  described  in  the  Informix  system  administration  manual  [Informix],  the  Database 
Administrator  will  create  and  maintain  databases  through  the  use  of  Informix  DBMS  conunands. 
Typical  tasks  would  include: 

•  Create  a  Database 

•  Create  the  Database  flles(tables)  and  fields(columns)  for  the  Database. 

•  Assign  the  appropriate  permissions  to  the  database  to  allow  application  connection 
through  the  Informix  HLI.  This  step  includes  adding  login  ids  and  users  as  necessary  to 
the  database  via  database  administrator  procedures. 

•  Set  any  default  values  and/or  integrity  constraints  on  table  fields. 

4.2  Creating  An  SDE  Library 

Once  an  appropriate  database  exists,  you  need  to  create  an  SDE  library  before  you  can  compile 
SAMeDL  source  code.  The  SDE  library  will  be  used  by  the  SAMeDL  compiler  to  store 
information  necessary  for  separate  compilation  and  also  to  act  as  a  repository  for  the  interface 
files  that  are  generate. 

You  create  a  new  SDE  library  with  the  sde.creatiib  conunand.  This  command  optionaUy  takes 
one  argument  which  is  the  directory  name  for  the  libra^;  if  you  do  not  specify  an  argument,  then 
the  lilmsuy  will  be  generated  in  your  current  working  directory. 


Intermetrics,  Inc. 


13 


SAMeDL  Development  Environment  -  User  Manual 


For  example,  to  create  an  SDE  library  in  the  directory  /usr/saine/example/saiiielib,  you  would 
issue  tihe  following  command: 

%sde.creatlib  /usr/seune/exem^le/sainelib 


In  order  to  create  the  library,  it  is  important  that  you  have  have  appropriate  read/write  privileges 
for  the  library  directory. 

43  Compiling  A  SAMeDL  Source  File 

The  next  step  is  to  prepare  a  SAMeDL  source  file  (with  the  text  editor  of  your  choice)  and 
compile  it  into  the  SDE  library. 

Before  you  can  use  the  compilo*  however,  you  must  properly  set  the  environnnent  variable 
INFORMIXDIR  to  contain  the  path  name  to  the  Informix  RDBMS  installation  directory  (e.g., 
/iisr/informix). 

Consider  the  following  description  which  is  assumed  to  be  in  the  file  bank.sme.  This  example 
contains  three  modules:  the  definition  module  samplemod,  the  schema  module  recdb,  and  the 
abstract  module  recdml.  Furdiermore,  the  example  dei^nds  on  the  definition  module 
sainedl_standard  which  must  have  been  previously  compiled  into  your  SAMeDL  library. 

— !  reference  sainedl_standard 

with  S2unedl_standard;  use  samedl_steuidard; 

definition  module  SanpleMod  is 

—  Member  Information 

domain  Member_Name  is  new  SQL_CHAR  Not  Null  (LENGTH  s>  30); 

domain  SSN  is  new  SQL_CHAR  Not  Null  (LENGTH  s>  9); 

domain  Age  is  new  SQL_SMALLINT  (  FIRST  =>  1,  LAST  =>  199.0); 

enumeration  SexEnum  is  (F,  M) ; 

domain  Sex  is  new  SQL_ENUMERATION_AS_CHAR  ( 

ENUMERATION  =>  SexEnum, 

WIDTH  =>  1, 

MAP  =>(m=>*B’,  f=>'A’)); 

dcmtain  Phone  is  new  SQL_CHAR  (LENGTH  =>  8) ; 
dcxnain  Street  is  new  SQL_CHAR  (LENGTH  =>  30); 
dcxnain  City  is  new  SQL^CHAR  (LENGTH  =>  15) ; 

d<xnain  County  is  new  SQL_CHAR  Not  Null  (LENGTH  »>  2); 

dcxnain  Club_Number  is  new  SQL_SMALLINT  Not  Null; 

exception  Record^Jlot_Found; 
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envuneration  Fail^pa  is  (Not_Logged_In,  SQl4_0k,  SQL_Fail); 

status  £etch_inap  named  is_£ound  uses  Failtype  is 
(  -999  ..  -300  =>  SQL_Fail, 

-299,  -298  =>  Not_Logged_In, 

0  =>  SQL_Ok, 

100  =>  raise  san^leniod.record^not_£ound) ; 

end  Seui^leMod; 


with  SampleMod;  use  SampleMod; 
schema  module  RecDB  is 

table  Members  is 

MemberName  not  null  :  Member_Nzune , 
MemberSSN  not  null  :  SSN, 
ClubNumber  not  null  :  Club_Number, 
MemberAge  :  Age , 

MemberSex  :  Sex, 

Member Phone  :  Phone, 

MemberStreet  :  Street, 

MemberCity  :  City, 

MemberCnty  not  null  :  County 
end  Members; 

end  RecOB; 


with  S^unpleMod;  use  Seui^leMod; 
extended  abstract  module  RecmL  is 
authorization  RecDB 


record  MeroberRec 
MemberNeune 
MemberSSN 
ClubNumber 
MemberAge 
MemberSex 
MemberPhone 
MemberStreet 
MemberCity 
MemberCnty 

end; 


Member_Neune ; 
SSN; 

Club_Nuinber; 

Age; 

Sex; 

Phone ; 
Street; 

City; 

Co\inty; 


procedure  CoimnitWork  is 
comnit  %rark; 

extended  procedure  connectRecdb  is 
connect  ‘ recdb ' ; 


procedure  Memberlnsert  is 

insert  into  RecDB. Members 
£rom  Row  :  MemberRec  VALUES; 

cursor  MemberSelect  (Req_MemberS5N  :  SSN)  £or 
select  MemberName, 
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Member SSM, 

CluliAlumber, 

Member Age , 

MemberSex, 

MemberPhone , 

MemberStreet , 

MemberCity, 

MeroberCnty 
from  RecDB. Members 

where  RecDB. Member s .MemberSSN  s  Req_Meii>berSSN; 
is 

procedure  Fetchit  is 

fetch  into  Row  :  MemberRec 
status  FetcbJMap  named  Rec_Status; 

end  MemberSelect; 

end  RecCML; 

The  SAMeDL  compiler  is  invoked  with  the  command  samedl.  For  example,  to  compile 
bank.sine  into  the  SDE  library  created  above,  you  should  issue  the  following  command; 

%samedl  -library  /usr/same/exeunple/samelib  bank.sme 


The  -library  qualifier  is  used  to  specify  the  name  of  an  existing  SDE  Ubrary;  this  is  optional,  and 
if  not  given,  the  library  will  be  assumed  to  exist  in  your  current  working  directory.  You  must 
give  the  host  filename  of  the  SAMeDL  input  source  file;  this  filename  must  end  with  the 
characters  ,sme.  For  more  information  on  invoking  the  SAMeDL  compiler,  refer  to  Chapter  5  of 
this  manual. 

The  SAMeDL  compiler  will  generate  interface  files  for  each  detinition  module  (an  Ada  package 
specification/body  pair)  and  each  abstract  module  (an  Ada  package  specification/body  pair,  a  C 
with  embedded  SQL  flle,  and  an  object  code  file).  No  int^ace  files  are  generated  for  schema 
modules.  All  interface  files  will  be  placed  in  the  samedl.lib  directory  contained  within  the 
library  directory.  Thus,  for  the  sample  compiler  invocation  above,  you  can  find  all  interface  files 
in  the  directory  /usr/same/example/sainelib/saiiiedl.lib. 

To  determine  what  the  names  of  the  generated  interface  files  for  the  modules  samplemod  and 
reedb,  you  can  use  the  sdeJs  command.  For  example: 

%sde.ls  -1  /usr/saroe/exeuqjle/samelib  -i  SAntplemod  recdml 

s^UI^leInod 

Interface  Files: 

/usr / seune / example / samel ib/ samedl .  lib/ P_2_ .  a  ( ADASPEC ) 
/usr/same/exanqple/samelib/samedl .  lib/B_2  .a  (ADABOOY) 


recdml 

Interface  Files: 

/usr/s2une/exekiiple/8amelib/ samedl . lib/P_3_.a  (ADASPEC) 
/U8r/same/example/samelib/samedl.lib/B_3 .a  (ADABODY) 
/usr/seune/exeunple/samelib/samedl . lib/E_l .ec  (EMBEDDEDC) 
/usr/seuDe/example/samelib/saffiedl . lib/E_l .o  (OBJECTFILE) 
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For  more  information  concerning  the  naming  conventions  used  for  SDE  library  files,  see  Section 

3.3  of  this  document 

4.4  Creating  An  Ada  Application  Program 

The  Ada  files  produced  by  the  SAMeDL  compiler  along  with  the  SAMeDL  standard  packages 
provide  an  abstract  Ada  interface  to  the  database  which  may  be  utilized  by  an  Ada  application 
program.  So  before  you  can  build  your  application,  you  first  need  to  compile  these  files  into  an 
appropriate  Ada  library  that  will  be  visible  to  your  Ada  application  development  library. 

The  SAMeDL  standard  packages  are  provided  as  part  of  SDE.  To  determine  the  location  of 
these  files  at  your  site,  please  refer  to  the  SDE  installation  notes  or  ask  your  system 
administrator. 

To  generate  an  “invoke”  command  file  for  compiling  the  Ada  interface  files  contained  in  your 
SAMeDL  library  into  your  Ada  library,  you  may  use  the  sde.inkscript  command.  For  example: 

%sde  .mkscript  -1  /usr/seune/example/samelib  -o  niy_script  seunplemcxi  recdml 
tmore  iny_script 

Compile  (Source  =>  * /usr/same/example/samelib/scunedl . lib/P_l_.a" ) ; 
Compile  (Source  =>  “ /usr/seune/example/seunelib/seunedl .  lib/B_l  .a” )  ; 

Compile  (Source  =>  * /usr/same/example/seunelib/seunedl . lib/P_2_ -a* ) ; 
Conpile  (Source  =>  * /usr/s^une/ex^unple/samelib/s^unedl .  lib/B_2  .a" )  ; 

Compile  (Source  =>  ■ /usr/same/ex^utlple/s^unelib/s^unedl .  lib/P_3_.a" )  ; 
Compile  (Source  =>  * /usr/s^une/ex^unple/s^unelib/s^unedl .  lib/B_3  .a* )  ; 

In  this  example,  the  sde.inkscript  command  indicates  that  3  sets  of  Ada  package  spcc/body  pairs 
need  to  be  compiled,  even  though  the  initial  compilation  of  the  file  containing  samplemod  and 
recdml  general  only  2  Ada  packages  spec/body  pairs.  The  reason  for  this  disaepancy  is  that 
the  definitional  module  samplemod  references  the  previously-compiled  module 
samedl_standard,  which  contains  the  definitions  of  the  base  domains  SQL_CHAR,  SQL_INT, 
etc.  The  reference  to  samedl_standard  is  achieved  via  a  reference  directive.  For  more 
information  on  compiler  directives,  see  Section  S.4  of  this  manual. 

To  generate  a  C-language  archive  including  all  of  the  C  object  files  peninent  to  your  Ada 
appheauon  you  may  use  the  sde.creatar  command.  For  example: 

%sde.creatar  c_recdml.a  recdml 

The  command  given  above  will  create  a  C-language  archive  named  c_recdml.a  which  contains 
the  C  object  code  necessary  to  link  the  Ada-Informix  interface  generated  by  the  SAMeDL 
abstract  module  recdml  to  an  Ada  application,  such  as  the  one  presented  below. 

Using  the  bank  example  presented  above,  suppose  that  you  need  a  utility  that  will  allow  bank 
tellers  access  to  profile  information  for  a  customer.  You  could  accomplish  this  with  the 
following  Ada  program: 

with  TEXT_IO; 
use  TEXT_10; 
with  SAMPLEMOD; 
with  RECDML; 
procedure  MAIN  is 
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—  User  I/O  information 

IN_BUFFER  ;  STRING (1  ..  80); 

LAST  :  NATURAL; 

OPT  :  INTEGER; 

—  Members  Row  Record 

ROW  :  RECDML.MQIBERREC; 

IROW  :  RECDML.MEMBERREC; 

procedure  DO_INS£RT  is 
begin 

PUT_LINE( •***  Function  to  Insert  rows  ***“); 

NEW_LINE; 

loop 

IN_BUPFER  :*  (others  =>  *  •); 

PUT (“Enter  Member  SSN  (9  char  nmx)  or  -1  for  MENU>  *); 
GET_LINE(IN_BUFFER.  LAST) ; 

NEW_LINE; 

exit  when  (IN_BUFFER(1  ..  LAST)  =  *-l'); 

IROW.MEMBERSSN  :=  SAMPLEMOD . SSN_NOT_NULL ( IN_BUFFER ( 1  ..  9)); 

IN_BUFFER  ;=  Cothers  =>  *  •); 

PUT( “Enter  Member  Name  (30  char  roeuc)>  “); 

GET_LINE(IN_BUFFER,  LAST) ; 

NEW_LINE; 

IROW.MEMBERNAME 

SAMPLEMOD .  MEMBER_NAME_NOT_NULL  ( IN_BUFFER  (1  .  .  30)); 

IN_BUFFER  :*  (others  =>  *  •); 

PUT( “Enter  Club  Number  (aaallint)>  •); 

GET_LINE(1N_BUFFER,  LAST) ; 

NEW_L1NE; 

IROW.CLUBNUMBER 

SAMPLEMOD .  CLUB JNUMBER_NOT_NULL '  VALUE  ( 

IN_BUFFER(1  ..  LAST)); 

IN_BUFFER  ;=  (others  *>  •  •); 

PUT( “Enter  Member  Age  (Smallint)  or  \\  for  MULL>  “); 
GET_LINE(IN_BUFFER,  LAST) ; 

NEW_LINE; 

if  (IN.BUFFERd  . .  2)  a  “\\“)  then 

SAMPLEMOD . AGE_OPS . ASSIGN ( IROW . MEMBERAGE , 

SAMPLEMOD. NULL_SQL_SMALLINT) ; 

else 

SAMPLBIOD . AGE_OPS . ASSIGN ( IROW . MEMBERAGE , 

SAMPLEMOD .  AGE_OPS .  WITH.NULL  ( 

SAMPLOlOD .  AGE_NOT_NULL '  VALUE  ( 

1N_BUFFER(1  ..  LAST)))); 

end  if; 

IN_BUFFER  :=  (others  a>  •  *); 

PUT( “Enter  Member  Sex  (M/F)  or  \\  for  NULL>  “); 
GET_LINE(IN_BUFFER,  LAST) ; 

NEW.LINE; 

if  (IN_BUFFER(1  ..  2)  a  “\\“)  then 
SAMPLEMOD.  ASSIGNdROW.MEMBERSEX, 
SAMPLB40D.MULL_SQL.ENUMERATI0N)  ; 
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else 

SAMPLEMOD.  ASSIGN  ( ZROW.MB4BERSEX, 

SAMPLEMOD . WITH_NULL ( 

SAMPLEMOD . SEX_>»T_NULL ■ VALUE ( 

IN_BUFFER{1  ..  LAST)))); 

end  if; 

IN_BUFFER  ;*  (others  =>  •  *); 

PUT ("Enter  Member  Phone  (8  chars)  or  \\  for  NULL>  *); 
GET_LINE(IN_BUFFER,  LAST) ; 

NEW_LINE; 

if  (IN_BUFFER(1  . .  2)  =  ’W)  then 

SAMPLEMOD .  ASSIGN  ( IROW  .MQ4BERPH0NE, 

SAMPLEMOD . NULL_SQL_CHAR ) ; 

else 

SAMPLEMOD . ASSIGN ( IRON . MEMBERPHONE , 

SAMPLEMOD . PHONE_OPS . WITH_NULL ( 

SAMPLEMOD . PHONE_NOT_NULL ( IN.BUFFER (1  . .  8 ) ) ) ) ; 

end  if; 

IN_BUFFER  : =  (others  =>  •  * ) ; 

PUT ("Enter  Member  Street  (30  char  max)  or  \\  for  NULL>  "); 
GET_LINE ( IN_BUFFER,  LAST) ; 

NEW_LINE; 

if  (IN_BUFFER(1  . .  2)  =  "\\")  then 

SAMPLEMOD.  ASSIC^KIROW.MQIBERSTREET, 

!  SAMPLEMOD. NULL_SQL_CHAR) ; 

else 

SAMPLEMOD . ASSIGN ( IRON .MQffiERSTREET , 

SAMPLEMOD . STOEET_OPS . WITH_NULL ( 

SAMPLEMOD. STREET_NOT_NULL ( IN_BUPPER (1  . .  30)))); 

end  if; 


IN_BUFFER  :=  (others  =>  *  *); 

PUT( "Enter  Member  City  (15  char  max)  or  \\  for  NULL>  "); 
GET_LINE(If«_BUFFER.  LAST)  ; 

NEW_LINE; 

if  (IN_BUFFER(1  ..  2)  =  "W")  then 
SAMPLEMOD  .ASSIOl  ( IRON  .MOiBERCITY , 

SAMPLEMOD. NULL_SOL_CHAR) ; 

else 

SAMPLEMOD .  ASSIC^j  ( IRON .  MEMBERCITY , 

SAMPLEMOD . CITy_OPS . WITH.NULL ( 

SAMPLEMOD . CITY_NOT_NULL ( IN_BUFFER (1  . .  15)))); 

end  if; 


1 


I 

f 


IN_BUFETR  :=  (others  =>  •  '); 

PUT( "Enter  Member  Cnty  (2  char  max)>  "); 
GET_LINE(IN_BUFFER,  LAST) ; 

NEWJLINE; 

IROW.MEMBERCNTY 

SAMPLQIOD .  COUNTY_NOT_NULL  ( IN_BUETER  (1  .  .  2 )  )  ; 


I 

I 


RECCML.MDlBERINSERTdROW)  ; 
RECDML .  CCMIMIIWORK; 
end  loop; 


f 

i 
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exception 

when  others  s> 

PUT_LINE(****  Error:  could  not  do  Insert  ****); 
end  DO_INSERT; 

procedure  DO_SELECT  is 

STATUS  :  SAMPLEMOD.FAILTYPE; 
begin 

PUT_LINE{''***  Function  to  Select  rows  ***■); 

NEW_LINE; 

loop 

IN_BUFFER  :=  (others  =>  •  •); 

PUT( ‘Enter  Member  SSN  (9)  or  -1  for  MENU>  ■); 

GET_LINE ( IN_BUFFER,  LAST) ; 

NEW_LINE; 

exit  when  {IN_BOFFER{l  ..  LAST)  =  ‘-I*); 

RECDML .  MEMBERSELECT .  OPEN  ( SAMPLEMOD .  SSN _NOT_NULL  ( 
IN_BUFFER(1  ..  9))); 

begin 

loop 

RECDML. MEMBERSELECT. FETCHIT (ROW,  STATUS) ; 

PUT_LINE(‘NAME:  -  &  STRING ( ROW. MEMBERNAME)  &  ‘ 
-SSN:  ■  &  STRING (ROW. MQfBERSSN)  &  ■ 

■CLUB:  •  Cc 

SAMPLEMOD . CLUB_NUMBER_NOT_NULL ' IMAGE ( 
ROW.CLUBNUMBER) ) ; 

PUTCAGE:  •); 

if  not  (SAMPLEMOD. IS_NULL (ROW.MQIBERAGE) )  then 
PUT (SAMPLEEKJD. AGEJNOT_NULL ’  IMAGE  ( 

SAMPLBJOD .  ACE_OPS .  WITHOUT_NULL  ( 
ROW.MBffiERAGE) ) ) ; 

end  if; 

SET_C0L(13) ; 

PUT (‘SEX:  •); 

if  not  (SAMPLBfOD.IS_NULL(ROW.MEMBERSEX) )  then 
PUT  ( SAMPLEMOD .  SEX_NOT_NULL  ‘  IMAGE  ( 

SAMPLEMOD. WITHOUT_NULL (ROW. MEMBERSEX) )  )  ; 
end  if; 

NEW_LINE; 

PUT( ‘PHONE;  •); 

if  not  ( SAMPLEMOD. IS_NULL( ROW. MQIBERPHONE ) )  then 
PUT ( STRING ( SAMPLQfOD . PHONE_OPS . WITHOUT.NULL ( 
^OW.MEMBERPHCWE) ) ) 
end  if; 

NEW_LINE; 


PUT( ‘STREET;  *); 

if  not  (SAMPLB<OO.IS_NULL(ROW.MEMBERSTREET) )  then 
PUT  ( STRING  (SAMPLB40D .  STREET.OPS .  WITHOUT_NULL  ( 
ROW.MEMBER5TREET) ) ) ; 
end  if; 

NEWJLINE; 
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PUTCCITY:  •); 

if  not  (SAMPLEMOD.IS.JtULL(ROW.MEMBERCZTY) )  then 
PUT  ( STRING  ( SAMPLQIOD ,  C  ITy_OPS .  WITHOUT JTOLL  ( 
ROW.MEMBERCITY) ) ) ; 
end  if; 

SET_COL(26) ; 

PUT_LINE( "COUNTY:  "  &  STRING{ROW.MEMBERCNTY)); 
NEW_LINE; 

PUT_LINE (•*********************************■) ; 
NEW_LINE; 
end  loop; 

exception 

when  others  => 

PUT_LINE("No  more  records  found!"); 

NEW_LINE; 

end; 

RECIML . MEMBERSELECT . CLOSE ; 

RECIML .  COMMITWORK  ; 

end  loop; 

exception 

when  others  =>  —  Couldn't  find  request 

PUT_LINE( "***  Error;  could  not  do  Select  ***"); 

end  DO_SELECT; 

begin 

RECim .  CONNECTRECDB  ; 
loop 

PUT_LINE("***  Option  Menu  ***"); 

PUT_LINE("  0  -  Quit"); 

PUT_LINE{"  1  -  Insert"); 

PUT_LINE("  2  -  Select"); 

PUT ("Option?  >  "); 

GET_LINE ( IN_BUFFER ,  LAST) ; 

NEW_LINE; 

OPT  :=  INTEGER' VALUE (IN_BUFFER(1  ..  LAST) ) ; 

case  OPT  is 
when  0  => 
exit; 
when  1  => 

DO_INSERT; 
when  2  => 

DO_SELECT; 
when  others  => 

PUT_LINE(" Illegal  Choice:  "  &  IN_BUFFER(1  ..  LAST) ) ; 
end  case; 

NEW_LINE(2) ; 
end  loop; 
end  MAIN; 
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Assuming  that  your  Alsys  Ada  development  library  is  in  /usr/same/example/adalib  and  that  the 
above  Ada  program  is  in  the  file  getprofa,  you  can  compile  and  link  the  program  by  performing 
the  following  steps,  which  use  the  file  myscript  and  the  archive  file  c_recdmlai  described  earlier 
in  this  section:  ~ 

•  Compile  the  SAMeDL  Standard  Packages  into  your  Ada  library  (this  step  may  be 
omitted  if  visibility  to  the  SAMeDL  Standard  Packages  has  been  gained  in  another 
way). 

%$SDEPATH/coinp_st<i_pkgs  /usr/saine/exainple/adalib 

•  Compile  the  code  generated  by  the  SAMeDL  compiler  into  your  library,  using  the 
script  generated  by  &e  sde.mkscript  command. 

%ada 

>  default .compile ( library=>/usr/same/ex2unple/adalib) 

>  invoke  ( f ile=>myscript ) 

>  quit 

•  Compile  your  application  into  the  Ada  library. 

%ada 

>  default .compile ( library=>/usr/same/ex^unple/adalib) 

>  compile  ( sources >getprof .ada) 

>  quit 

•  Generate  the  executable  using  the  Alsys  BIND  command.  When  issuing  the  BIND 
command,  include  the  following  arguments  in  addition  to  providing  values  for  the 
required  PRCXSRAM  and  LIBRARY  parameters  [AdaRef]: 

(a)  SEARCH  =>  the  archive  file  generated  by  the  call  to  sde.creatar  (for  this 
example,  c  recdmia), 

$INFORMkXDIR/Ub/libsql4,a, 

SINFORMIXDlR/UbAibfesqU, 

/lib/Ubx^ 

•  The  order  of  arguments  for  the  MODULES  parameter  is  not  significant,  but  the  order  of 
arguments  for  the  SEARCH  parameter  is  significant.  If  your  application  program 
requires  additional  external  modules,  you  may  have  to  reorder  the  list  of  external 
mc^ules  before  all  references  can  be  adequately  resolved.  Consult  the  Alsys  Ada 
User's  Manual  for  further  informadon. 

In  the  example  above,  the  Unix  C-shell  (csh)  script  comp_std  pkgs  provided  with  SDE  contains 
Alsys  Ada  Compiler  commands  and  is  described  in  Section  S3  of  this  document  (SDEPATH  is 
an  environment  variable  which  has  been  set  to  the  path  name  for  the  SDE  installation  directory). 
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Chapter  5  Building  Ada/SQL  Interfaces  With  SAMeDL 

5.1  Overview  Of  The  SAMeDL  Compiler 

The  SAMeDL  compiler  is  used  to  generate  interface  files  representing  an  Ada/SQL  interface  for 
your  Ada  applications.  These  interface  files  consist  of  one  or  more  files  containing  Ada 
packages  representing  the  Ada  interface: 

•  Each  definition  module  defined  in  the  source  input  will  have  an  Ada  package 
specification  and  a  corresponding  Ada  package  body  generated. 

•  Each  abstract  module  defined  in  the  source  input  will  have  an  Ada  package 
specification  and  a  corresponding  Ada  package  body  generated. 

In  addition,  for  each  abstract  module  a  corresponding  concrete  module  will  be  generated.  This 
file  takes  the  form  of  C  code  with  embedded  Informix  SQL  statements.  Procedures  declared 
within  the  file  are  called  by  procedures  within  the  abstract  module's  Ada  package  body  in  order 
that  direct  interaction  with  the  database  can  be  handled.  Each  such  file  will  be  preprocessed  by 
the  Informix  SQL  C  preprocessor  and  the  resulting  output  will  be  compiled  by  the  C  compiler 
resulting  in  a  corresponding  object  code  file  (a  .o  file). 

The  SAMeDL  compiler  operates  within  the  context  of  an  SDE  library.  The  library  maintains 
dependency  information  and  other  data  used  by  the  compiler  to  perform  separate  compilation.  In 
addition,  the  SDE  library  acts  as  a  repository  for  all  interface  files  generated  by  the  SAMeDL 
compiler. 

5.2  SAMeDL  Compiler  Invocation 

The  SAMeDL  compiler  is  invoked  with  the  command  samedl.  It  accepts  a  series  of  options  and 
a  single  file  name  as  input  arguments.  Option  keywords  are  not  case  sensitive  and  may  be 
truncated  as  long  as  the  resulting  abbreviation  is  unambi^ous.' 

Syntax 

samedl  [options]  source Jile 

Options 


•library  pathname  Operate  in  the  SDE  library  pathname.  If  not 

specified,  will  default  to  current  working 
directory 

-list  Generate  an  interleaved  listing  file 

•syntax  Check  the  syntax  of  the  input  file  without 

generating  any  output  files. 


samedl  executes  the  SAMeDL  compiler  and  compiles  the  named  SAMeDL  source  file  into  the 
SDE  library  directory  qiecified  by  pathname;  if  pathname  is  not  specified,  then  it  will  default  to 
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the  current  working  directory.  Note  that  the  SDE  library  must  already  have  been  created  (via  the 
sde.creatlib  command).  The  SAMeDL  source  file  name  must  end  with  the  suffix  ^me. 

The  listing  option,  when  specified,  directs  the  compiler  to  produce  an  interleaved  listing  file. 
The  listing  file  will  be  named  <x>.lis  where  <x>  is  the  base  name  of  the  input  source  file  (for 
example,  a  source  file  named  xyz,sme  will  result  in  a  listing  file  being  named  xyz.lis).  Compiler 
diagnostic  messages  will  always  be  written  to  standard  output,  regardless  of  whether  or  not  -list 
is  in  effect. 

The  syntax  option,  when  specified,  causes  the  SAMeDL  compiler  to  act  as  a  SAMeDL  syntax 
checker,  generating  error  messages  for  syntax  and  some  semantic  errors,  but  no  code. 

The  SAMeDL  compiler  will  generate  interface  files  for  each  definition  module  (an  Ada  package 
specification/body  pair)  and  each  abstract  module  (an  Ada  package  specification/body  pair,  a  C 
with  embedded  SQL  file,  and  an  object  code  file).  No  interface  files  are  generated  for  schema 
modules.  All  interface  files  will  be  placed  in  the  samedl.lib  directory  contained  within  the 
libra^  directory.  For  the  naming  conventions  used  for  interface  files,  please  refer  to  Section  3.3 
in  this  manual. 

As  an  example,  take  the  following: 

%sainedl  -lib  /usr /scune/example/samelib  -list  exeonple . sme 


This  will  compile  the  SAMeDL  description  file  example. sme  into  the  library 
/usr/same/example/samelib  and  create  an  interleaved  listing  file  named  exampleJis  in  the 
current  directory.  All  eenerated  interface  files  will  be  placed  in  the  directory 
/usr/same/example/samelib^fnedl.lib. 

Before  invoking  the  SAMeDL  Compiler,  users  should  be  sure  to  check  that  SAMeDL  packages 
required  via  reference  directives  have  already  been  compiled  into  the  SAMeDL  library.  In 
particular,  a  typical  SAMeDL  code  file  will  include  reference  directives  for  the  SAMeDL 
definitional  modules  SAMeDL_Standard  and  SAMeDL  System,  found  in  the  files 
$SDEPATH/STD_PKGS/samedr std.sme  and  $SDEPATH/STD_PKGS/samedl_sys.sme. 
These  packages  contain  definitionsTor  system  limits  and  predefined  base  domains.  Users  who 
tend  to  frequently  use  the  predefined  base  domains  should  get  into  the  habit  of  compiling  these 
files  into  their  SAMeDL  libraries  at  library  creation  time. 

Before  you  can  use  the  compiler  however,  you  must  properly  set  the  environment  variable 
INFORMIXDIR  to  contain  the  path  name  to  the  Informix  RDBMS  installation  directory  (e.g., 
/usr/informix). 

S3  Using  the  Compiler-Generated  Interface 

In  order  to  use  the  SAMeDL  compiler  generated  Ada/SQL  interface,  the  target  Ada  application 
must  be  linked  with  the  SAMeDL  generated  Ada  files  and  object  code  files,  a  set  of  SAMeDL 
standard  packages  (see  Section  3.5),  a  set  of  Informix  Libraries,  and  a  Unix  C  library  .To 
facilitate  the  final  steps  in  building  the  Ada  target  application,  SDE  provides  you  with  a  Unix  C- 
shell  script  that  contains  Alsys  Ada  Compiler  commands.  This  script  can  be  found  in  the  SDE 
instaUation  directory  and  used  as  an  example  of  how  to  compile  the  SAMeDL  Standard  Packages 
your  application  requires  using  the  Alsys  Ada  Compiler.  It  is  called  comp_std_pkgs. 

The  first  step  in  compiling  and  linking  your  application  is  to  make  the  SAMeDL  standard 
packages  visible  to  your  Alsys  Ada  application  library.  This  can  be  done  by  using  the 
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comp_std_pkgs  script  rile  found  in  the  SDE  installation  directory.  You  nnay  invoke  the 
comp~std3lK8S  by  issuing  die  following  command: 

%coii^_stcLp)cgs 


where  iibpath  is  the  pathname  to  the  Ada  library  that  the  SAMeDL  standard  pacl^es  are  to  be 
compiled  into.  This  script  will  compile  all  of  the  SAMeDL  standard  packages  into  your  Ada 
library.  This  step  needs  to  be  performed  on(%  per  library,  unless  the  SAMeDL  standard  packages 
have  already  been  made  visible  to  the  Ada  libr^  in  some  other  way. 

Once  the  standard  packages  have  been  compiled  into  the  Ada  library,  the  SAMeDL-goiaated 
Ada  packages  should  be  compiled  into  the  library.  The  SDE  command  sde.mkscript  can  be 
used  to  generate  a  script  rile  for' performing  this  compilation.  Refer  to  section  8.6  of  this 
document  for  instructions  and  examples. 

After  the  SAMeDL  interface  code  has  been  compiled  into  your  library,  you  may  use  the  Alsys 
Compile  command  to  compile  your  application  into  the  library.  Once  this  step  has  been 
completed,  you  are  ready  to  prepare  for  linking  die  Ada-lnformix  executable. 

There  are  four  riles  which  must  be  linked  with  your  application  in  order  to  produce  a  valid 
executable.  Two  of  the  files,  namely  $INFORMIXDIR/lib/libsql4a  and 
$INFORMIXDIR/lib/libfesql.a  are  Informix  libraries.  One  of  the  riles,  /lib/libx.a,  is  an 
Interactive  Unix  C  library.  And  the  fourth  rile  is  an  archive  of  the  pertinent  C  object  code 
generated  by  the  SAMeDL  compiler  and  stored  in  the  SAMeDL  library.  This  last  rile  is  created 
from  the  SAMeDL  library  information  using  die  command  sde.creatar,  described  in  section  8.3 
of  this  document 


Your  Ada  application  can  be  linked  easily  by  following  these  simple  instructions: 

•  Generate  the  executable  using  the  Alsys  BIND  command.  When  issuing  the  BIND 
command,  include  the  following  arguments  in  addition  to  providing  values  for  the 
required  PRCX3RAM  and  LIBR/^Y  parameters  [AdaRef]' 


(a)  SEARCH  => 


the  archive  file  generated  by  the  call  to  sde.creatar  (for  this 
example,  c  recdmloi), 

$INFORMlXDIR/lib/libsql4J^ 

$INFORMlXDIR/lib/libfesql.a, 

/Iib/libx4i 


•  The  order  of  arguments  for  the  MODULES  parameter  is  not  significant  but  the  order  of 
arguments  for  the  SEARCH  parameter  is  significant  If  your  application  program 
requires  additional  external  modules,  you  may  have  to  reorder  the  list  of  external 
modules  before  all  references  can  be  adequately  resolved.  Consult  the  Alsys  Ada 
User's  Manual  for  further  information. 


5.4  Compiler  Directives 

Compiler  directives  are  embedded  in  SAMeDL  source  files  and  are  used  to  indicate  special 
directions  to  the  compiler  outside  of  the  SAMeDL  syntax  and  semantics.  The  goieral  form  of 
any  directive  is; 


latermetrics,  Inc. 


25 


SAMeDL  Development  Environment  -  User  Manual 


-ldirective_nanie  parameterjist 


In  order  for  a  directive  to  be  recognized,  it  is  important  that  no  white  space  (i.e.,  spaces,  tabs, 
etc.)  appear  between  any  of  the  dashes  (-),  the  bang  (!),  and  the  directive  name  keyword. 

Each  directive  will  be  given  in  its  general  form,  followed  by  a  definition  of  each  term  of  the 
directive,  and  a  description  of  its  use. 

5.4.1  Reference  Directive 

The  reference  directive  allows  you  flexibility  of  separate  compilation  by  permitting  visibility  of 
externally  declared  modules  that  have  been  previously  compiled.  This  directive(s)  must  appear 
inunediately  before  the  first  context  clause  of  a  SAMeDL  m^ule. 

The  compiler  processes  the  reference  directive  by  reading  the  referenced  module  from  the  SDE 
library  currently  in  context  and  importing  the  appropriate  symbol  information  for  the  referenced 
module.  Once  a  reference  directive  is  used  for  a  particular  module,  then  any  module  appearing 
textually  after  the  reference  directive  may  refer  to  the  contents  of  the  referenced  module. 

Typical  use  for  the  reference  directive  is  to  gain  visibility  to  the  SAMeDL  packages 
SAMeDL_Standard  and  SAMeDL_System,  which  contain  the  definitional  modules  for  the 
predefined  base  domains  and  the  system  limits. 

The  form  ^  the  reference  directive  is  as  follows: 

-Inference  module_name 


The  reference  keyword  must  begin  inunediately  following  the  !  and  the  entire  word  must  be 
included.  The  keyword  is  case-insensitive,  module.name  must  reference  the  name  of  a 
SAMeDL  module  that  has  been  previously  compiled  into  the  SDE  library. 

Afote:  This  directive  must  be  placed  before  the  context  clauses  of  a  module  declaration;  placing 
it  between  the  start  of  a  module  declaration  and  the  corresponding  END  will  cause  a  fat^  error. 
Also,  this  directive  will  not  compile  the  referenced  module.  Any  module  that  needs  to  be 
compiled  or  re-compiled,  needs  to  be  done  so  separately. 

As  an  example,  assume  the  following  definitional  and  schema  modules  have  been  previously 
compiled. 

DEFINITION  MODULE  Bank_Def  IS 

DOMAIN  Customer^name.domain  IS  NEW  SQL_CHAR ( length  s>  50); 


END  Bank_De£; 

WITH  Bank_Def; 

USE  Bank_De£; 

SCHEMA  MODULE  BankDB  IS 
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END  BankDB; 


Then  the  following  Abstract  module  would  have  full  visibility  to  both  modules  using  the 
reference  directive: 

— IRAfarane*  bank_def 
—  I  R*f arMiea  bankdb 
WITH  Bank_Def; 

USE  Bank_Def; 

ABSTRACT  MODULE  Bank.Actions  IS 
AUTHORIZATION  BankDB 


END  Bank_actions; 

5.4^  Owner  Directive 

The  owner  directive  enables  you  to  specify  the  Informix  owner  of  a  particular  set  of  database 
tables.  The  owner  directive  must  precede  a  schema  module  declaration  and  a^ects  that  schema 
module  in  the  following  way:  the  owner_name  specified  in  the  directive  is  considered  to  be  the 
name  of  the  Informix  owner  of  the  database  tables  defined  in  the  schema  module.  Each  owner 
directive  applies  only  to  the  next  schema  module  declaration  in  the  SAMeDL  source  code.  If  no 
owner  is  sp^ified  for  a  particular  schema  module,  then  the  owner  is  assumed  (by  Informix)  to  be 
the  user-name  of  the  account  from  which  the  ai^lication  is  being  run  at  the  time  of  connection  to 
the  database  server. 

The  format  of  the  owner  directive  is  as  follows: 

-{owner  owner  name 


The  keyword  owner  must  begin  immediately  following  the  !  and  the  entire  word  must  be 
included.  The  keyword  is  case-insensitive. 

Note:  This  directive  must  be  placed  outside  of  any  module  declaration;  placing  it  between  the 
start  of  a  module  declaration  and  the  corresponding  END  will  cause  a  fatal  error.  The  most 
logical  place  to  put  the  directive  is  directly  before  a  schema  module  declaration,  as  shown  below. 

As  an  example,  use  of  the  Owner  Directive,  as  exhibited  below,  would  cause  the  resulting  Ada- 
Informix  application  to  access  the  table  myiiserid.Cust,  owned  by  user  myuserid: 


~-IOiRMr  ayusBrid 
WITH  Bank_D®f; 

USE  Bank_De£; 

SCHEMA  MODULE  BankDB  IS 

TABLE  Cust  IS  —  Basic  custoner  infomation 
Name  :  Custonier_nanie_dc»nain, 

SSN  :  SSN.domain, 


Intermetrics,  Inc. 


27 


SAMeDL  Development  Environment  -  User  Manual 


Street_acldr  :  Addr.domain, 

City.addr  :  Addr_domain, 

State^addr  :  State_^canain 
END  Cust; 

END  BankDB; 

WITH  B*mK_Def; 

USE  BanK_De£; 

ABSTRACT  MODULE  Bank^Actions  IS 
AUTHORIZATION  BankDB 

PROCEDURE  Get_custcaner_pro£ile  (  SSN_IN  :  SSN.domain  )  IS 
SELECT  * 

INTO  CustOTier_pro£ile  ;  customer_record 
FRCM  BankDB. Cust 
WHERE  SSN  =  SSN_in; 

END  Bank_actions; 


Note:  Successful  use  of  the  Owner  Directive  requires  that  the  resulting  Ada-DBMS  application 
be  run  from  an  account  which  has  been  granted  the  appropriate  privileges  for  all  referenced 
tables.  Refer  to  the  Informix  user's  guides  [Informix]  for  more  iitformation  on  privileges  and 
owners. 


28 


Intermetrics,  Inc. 


Chapter  6  -  Implementation  Dependent  Features 


Chapter  6  Implementation  Dependent  Features 

This  chapter  describes  SAMeDL  features  which  are  dependent  on  the  Informix  implementation. 
Section  6.1  describes  features  which  are  included  as  part  of  the  SAMeDL  language  ([LRM])  but 
not  supported  due  to  limitations  imposed  by  Informix.  Section  6.2  details  features  which  are  not 
includ^  as  part  of  the  SAMeDL  but  are  provided  as  extensions  for  the  implementation  either 
because  of  necessity  or  convenience.  Finally,  Section  6.3  includes  some  solutions  to  system 
errors  that  are  commonly  encountered. 

6.1  SAMeDL  Language  Limitations  Under  Informix 

Because  of  limitations  imposed  by  Informix,  use  of  the  following  features  described  in  the 
SAMeDL  Language  Reference  Manual  ([LRM])  will  produce  errors  (all  references  below  are 
made  with  respect  to  [LRM]): 

1.  Queries  with  the  UNION  operator  -  in  Section  5.4,  the  query  term  and  query 
expression  arguments  to  the  UNION  operator  can  both  be  parenthesized,  in  accordance 
with  the  grammar  of  SQL.  Informix  does  not  support  the  use  of  parenthesized 
expressions  as  operands  to  the  UNION  operator,  so  an  error  will  be  produced  by 
Informix  during  the  precompilation  of  the  embedded  C/ESQL  if  this  feature  of 
SAMeDL  is  used. 

2.  WHERE  Clauses  •  The  SAMeDL  language,  in  accordance  with  the  ANSI  SQL 
Standard,  allows  input  references  to  be  part  of  value  expressions,  regardless  of  whether 
or  not  the  input  reference  is  to  a  null-bearing  parameter.  However,  Informix  does  not 
allow  null-bearing  input  references  to  be  part  of  where  clauses  or  appear  in  cursors. 
The  SAMeDL  compiler  will  issue  an  error  if  a  null-bearing  parameter  is  used  in  a  place 
where  Informix  does  not  allow  it 

6.2  SAMeDL  Extensions  For  Informix 

This  section  details  features  which  are  included  as  part  of  SAMeDL  as  implementation-specific 
extensions  either  because  of  necessity  or  convenience.  They  include  the  following  statements: 

Connect  Statement 

The  connect_statement  is  an  extended  statement.  It’s  grammar  consists  of  the  following 
productions: 

connect.statement  ::s  connect  database_name ; 

database.name  ::s  characterjiteral  | 

constant_referenc8 

The  Connect  Statement  connects  the  application  to  the  Informix  database  named  database  name. 
The  user  running  the  application  must  have  Connect  privileges  for  the  given  database.  All 
subsequent  transactions  are  performed  on  the  connected  database,  until  a  new  Connect  statement 
is  issued.  No  SAMeDL-generated  application  interface  can  access  Informix  data  without 
successful  connection  to  an  Informix  database. 

Because  the  Connect  statement  is  an  extended  statement,  its  containing  procedure  and  abstract 
module  must  also  be  marked  as  extended. 
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Deflnitional  Module  Bodies 

The  SAMeDL  Compiler  generates  a  package  body  for  each  definitional  module.  This  practice 
differs  from  the  recommendation  of  Ae  S/^eDL  LRM,  but  is  maintained  in  order  to  decrease 
code  size  and  functional  redundancy. 

The  package  body  for  each  definitional  module  is  empty  unless  the  definitional  module  contains 
a  domain  declaration  of  data  class  enumeration  possessing  a  uso'-defined  database  mapping  as  a 
value  for  the  predefined  parameter  MAP.  For  each  declaration  of  this  type,  a  function  to  p«^orm 
conversion  from  the  domain  type  to  the  underlying  database  type  is  provided.  A  function  to 
convert  from  the  database  type  to  the  domain  type  is  also  provided.  Without  these  globally 
accessible  functions,  a  large  amount  of  code  would  have  to  be  reproduced  frequently  in  the 
Abstract  Module's  package  body  in  order  to  perform  data  conversions. 

These  functions  can  be  accessed  by  the  SAMeDL  application,  but  are  primarily  designed  for  use 
by  the  SAMeDL  compiler  back-end  to  generate  package  bodies  for  Abstract  Modules. 

63  Troubleshooting  Common  System  Errors 

The  following  list  includes  some  helpful  techniques  for  configuring  the  SAMeDL  environment 
that  will  reduce  your  chances  of  getting  some  common  system  errors. 

1.  Increase  the  MAXUMEM  Interactive  Unix  kernel  parameter  -  If  you  get  an 
Informix  error  message  when  running  your  application  that  indicates  that  your 
application  process  does  not  have  enough  memory  available  to  run  successfully,  then 
you  should  increase  the  MAXUMEM  kernel  parameter.  Consult  your  Unix  system 
administrator  for  instructions. 

2.  Increase  the  Interactive  Unix  ULIMIT  kernel  parameter  -  If  you  get  an  Alsys  error 
message  during  the  LISTING  phase  of  compiling  your  application,  then  you  might  tty 
raising  the  ULIMIT  kernel  parameter  to  increase  the  file  size  limit  Consult  your  Unix 
system  administrator  for  instructions. 
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Chapter  7  Tool  Limitations 

This  chapter  lists  limitations  of  SDE. 

7.1  SAMeDL  Compiler  Limitations 

The  following  limitations  are  imposed  by  the  SAMeDL  compiler: 

•  The  maximum  number  of  characters  allowed  in  a  source  line  is  2SS. 

•  The  compiler  will  not  delete  any  files  from  an  SDE  library;  the  sde.purge  command 
must  be  used  to  clean  the  library  of  any  out  of  date  or  temporary  files. 

•  The  maximum  length  of  an  Error  Message  that  can  be  printed  by  the 
Process.Database.Error  routine  is  132  charactCTS. 

•  If  extremely  long  names  are  used  in  the  SAMeDL  source  code,  it  is  possible  that  the 
compiler  could  attempt  to  generate  output  with  lines  that  exceed  the  Unix  line  lengA 
limit  The  SAMeDL  compiler  will  issue  a  warning  if  excessive  name  length  results  in 
an  output  problem. 

•  The  value  range  for  types  Smallint  and  Indicator_Typc  is  -32768 ..  32767. 

•  The  value  range  for  types  Int  and  Sqlcode_Type  is  -2147483648  ..  2147483647. 

•  The  value  range  for  type  Real  is  the  range  for  Alsys’  LONG.FLOAT  type. 

In  addition,  because  Ada  source  is  generated  by  the  SAMeDL  compUer,  all  restrictions  and 
semantics  as  outlined  in  [Ada]  and  [AdaRefj  must  be  followed.  Although  these  limits  are  not 
explicitly  checked  by  the  SAMeDL  compiler,  they  do  indirectly  affect  the  structure  of  what 
normally  would  be  legal  SAMeDL  code. 

7.2  SDE  Module  Manager  Limitations 

The  following  limitations  are  imposed  by  the  SDE  Module  Manager: 

1 .  The  SDE  conunands  (with  the  exception  of  sde.purge)  will  not  delete  any  fries  from  an 
SDE  library;  the  sde.purge  command  must  be  used  to  clean  the  library  of  any  out  of 
date  or  temporary  fries. 

2.  After  executing  the  sde.purge  command,  you  may  not  restore  the  library  to  its  prior 
state. 
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Chapter  8  SDE  Command  Reference  Manual  Pages 

This  chapter  contains  a  reference  guide  for  each  of  the  commands  in  SDE.  The  commands 
available  to  you  are; 

invoke  the  SAMeDL  compiler 
reinitialize  an  SDE  library 

create  a  library  archive  file  for  compiled  concrete  modules 
create  an  SDE  library 
list  compiled  SAMeDL  modules 

generate  an  Ada  compilation  script  file  for  an  interface  fde 
remove  out  of  date  files  from  an  SDE  library 
remove  a  SAMeDL  module  from  an  SDE  library 
remove  an  SDE  library 


samedi 

sde.cleanlib 

sde.creatar 

sde.creatlib 

sde.ls 

sde.inkscript 
sde.  purge 
sde.rm 
sde.rinlib 
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8.1  samedl 
Command 

samedl  -  invoke  the  SAMeDL  compiler 

Syntax 

samedl  [options]  source  Jile 

Options 

-library  pathname  Operate  in  the  SDE  library  pathname.  If  not 

specified,  will  default  to  current  working 
directory 

-list  Generate  an  interleaved  listing  file 

-syntax  Check  the  syntax  of  the  input  file  without 

generating  any  output  files. 

Description 

samedl  exec^^tes  the  SAMeDL  compiler  and  compiles  the  named  SAMeDL  source  file  into  the 
SDE  library  directory  specified  by  pathname-,  if  pathname  is  not  specified,  then  it  will  default  to 
the  current  working  directory.  The  S  AMeDL  source  file  name  must  end  with  the  suffix  jsme. 

The  listing  option,  when  specified,  directs  the  compiler  to  produce  an  interleaved  listing  file. 
The  listing  flle  will  be  named  <x>.lis  where  <x>  is  the  base  name  of  the  input  source  file  (for 
example,  a  source  file  named  xyzjsme  will  result  in  a  listing  file  being  named  xyz.lis).  Compiler 
diagnostic  messages  will  always  be  written  to  standard  ouqmt,  regar&ess  of  whether  or  not  -list 
is  in  effect 

The  S  AMeDL  compiler  wiU  generate  interface  files  for  each  definition  module  (in  the  form  of  an 
Ada  package  si^ification/body  pair)  and  each  abstract  module  (in  the  form  of  a  layered 
interface  consisting  of  an  Ada  package  specification/body  pair  and  an  object  code  file  generated 
from  a  C  with  embedded  SQL  file).  No  interface  files  are  generated  for  schema  modules.  All 
interface  files  will  be  placed  in  the  S AMeDL  Ubraiy  contain^  within  the  library  directory. 

Before  using  the  compiler,  the  environment  variable  INFORMDCDIR  must  be  properly  set  to 
contain  the  path  name  to  the  Informix  RDBMS  installation  directory  (e.g.,  /iisr/informix). 
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File  Name 

Description 

Definitional  Module 

D_xxxxx.sme 

Text  file  containing  SAMeDL  source  code 
representing  the  definitional  module 

P_xxxxx_.a 

Generated  Ada  package  specification  file 

B_xxxxx.a 

Generated  Ada  package  body  file 

Schema  Module 

S_xxxxx.sme 

Text  file  containing  SAMeDL  source  code 
representing  the  schema  module 

Abstract  Module 

A_xxxxx.sme 

Text  file  containing  SAMeDL  source  code 
representing  the  abstract  module 

P_xxxxx_.a 

Generated  Ada  package  specification  file 

B_xxxxx.a 

Generated  Ada  package  body  file 

E_xxxxx.cc 

Generated  C  w/  embedded  SQL  (C/ESQL) 
fUe 

E_xxxxx.o 

Object  code  for  the  expanded/compiled 
C/ESQL  file 

where  xxxxx  denotes  a  unique  integer. 

Diagnostics 

The  diagnostics  produced  by  the  S AMeDL  compiler  are  intended  to  be  self-explanatory. 
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8.2  sde.cleaDlib 
Command 

sde.cleanlib  -  reinitialize  a  SDE  library 

Syntax 

sde.cleanlib  \pathname\ 

Description 

sde.cleanlib  will  empty  an  existing  SDE  library  of  all  compilation  information.  The  command 
will  re-initialize  the  nanies.dbe  and  samedl.dat  files  and  remove  the  remaining  contents  of  the 
samedl.lib  directory  from  the  directory  specified  by  pathname-,  if  pathname  is  not  specified,  tiien 
it  will  default  to  the  current  working  directory. 

Examples 

The  following  sequence  of  commands  cleans  and  re-initializes  the  library  contained  in  the 
directory  /home/samedl. 

%cd  /ho!ne/s2unedl 
%sde.cle2mlib 


The  following  command  does  the  same  thing: 

%sde.cleanlib  /home/seunedl 


Diagnostics 

An  error  is  reported  and  no  action  is  taken  if  pathname  does  not  specify  a  valid,  unlocked  SDE 
library. 
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83  sde.creatar 
Command 

sde.creatar  -  create  a  library  archive  file  for  compiled  concrete  modules 

Syntax 

sde.creatar  [options]  archive jtame  module jiame  ... 

Options 

■library  pathname  Operate  in  the  SDE  library  pathname.  If  not 

specified,  will  default  to  current  working 
duectoiy 


Description 

For  each  SAMeDL  abstract  module  specitied  by  module  jiame,  sde.creatar  will  add  (or 
replace)  the  object  code  file  representing  the  related  concrete  module  into  the  library  archive  ffle 
denoted  by  archive  jiame.  The  library  archive  file  may  already  exist,  or  in  the  event  that  it  does 
not  exist,  a  new  one  will  be  created.  sde.creatar  is  analogous  to  the  following  UNIX  conunand: 

%ar  r  archive_mune  c_module_munel .  o  ~ 


See  ar(l)  in  the  UNIX  Programmer's  Manual. 

Examples 

The  following  exanqple  adds  the  concrete  modules  associated  with  the  SAMeDL  abstract 
modules  absl  and  abs2  (assume  they  are  E_l.o  and  E_2.o  respectively)  from  the  library 
/usr/bome/jdoe/myjib  to  the  archive  file  my^rcbive  in  Recurrent  worldng  directory. 

%sde.creatar  -lib  /usr/home/jdoe/niy_lib  iny_archive  absl  abs2 


Assuming  that  my_archive  was  previously  empty  or  did  not  exist,  then  issuing  the  UNIX 
command  ar  with  die  table  of  contents  (t)  option  wUl  yield  the  following  results: 

%ar  t  .  /iny_archive 

E_l.o 

E_2.o 


Diagnostics 

An  error  is  reported  and  no  action  is  taken  if  modulejuune  is  not  an  abstract  module  or  does  not 
exist  in  the  library,  or  if  the  library  is  not  valid  or  is  locked. 
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8.4  sde.creatlib 
Command 

sde.creatlib  •  create  an  SDE  library 

Syntax 

sde.creatlib  \pathname] 

Description 

sde.creatlib  creates  and  initializes  a  new  SDE  library.  It  creates  a  directory  named  samedMib 
for  die  litoary  in  the  directory  specified  by  pathname.  If  pathname  is  not  given,  the  current 
working  directory  is  the  default 

The  command  creates  the  files  samedLdat  and  name&dbe  in  the  samedLIib  directory  and  sets 
the  their  information  fields  to  an  initial  state. 

Examples 

The  following  sequence  of  commands  creates  a  new  SDE  module  manager  library  in  the 
directory  /hoi^samedl. 

%cd  /hoine/sainedl 
%sde.cr«atlib 


The  following  command  does  the  same  thing: 

%sde.cr«atlib  /home/sainedl 


Diagnostics 

An  error  is  generated  and  no  action  is  taken  if  pathname  is  not  an  existing  directory  or  if  the 
direaory  already  contains  an  SDE  library. 
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8.5 


Command 


sde.ls  -  list  compiled  S  AMcDL  modules 


Syntax 

sde.ls  [options]  [rnodulejiame]  ... 


Options 
>ada_only 
•interface 
•library  pathname 

•verbose 


List  only  generated  Ada  interface  tiles 

List  all  generated  interface  tiles 

Operate  in  the  SDE  library  pathname.  If  not 
specitied,  will  default  to  current  working 
directory 

List  tile,  tile  type,  library  entry  date,  source  tile 
name,  and  library  tile  name. 


Description 

sde.ls  provides  a  list  of  the  S  AMeDL  modules  con^iled  in  the  sptxitied  SDE  library  denoted  by 
pathname  (or  the  current  working  directory  if  pathname  is  not  given).  Options  are  provided  to 
give  more  or  less  extensive  information. 

Specifying  one  or  more  module  names  gives  information  only  on  those  modules;  otherwise 
information  for  all  modules  in  the  library  vnll  be  listed. 

The  options  -ada_only  and  -interface  are  mutually  exclusive.  If  both  are  specified,  then  • 
interface  will  be  in  effect 

Examples 

The  following  command  lists  all  (verbose)  information  for  the  modules  absl  and  abs2  and  their 
generated  interface  tiles  from  die  library  in  the  current  working  directory. 

%sde.ls  -V  -i  absl  <U3s2 
absl 

Unit  Kind:  ABSMODULE 
Source  File:  edTsl.srae 
Library  File:  ./saiiiedl.lib/A_l.sine 
Tine  Entered:  Feb  24  1992  11:59 
Interface  Files: 

. /sanedl . lib/P_2_.a  (ADASPEC) 

./sanedl.lib/B_2.a  (ADABODY) 

./ sanedl. lib/E_l.ec  (EMBEIX}EDC) 

./ sanedl. lib/E_l.o  (OBJECTFILE) 
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abs2 

Unit  Kind:  ABSMODULE 
Source  File:  abs2.siiie 
Library  File:  ./sainedl.lib/A_2.sine 
Time  Entered:  Feb  24  1992  12:00 
Interface  Files: 

./saniedl.lib/P_3_.a  (ADASPEC) 
./sainedl.lib/B_3.a  (ADABODY) 
./sainedl.lib/E_2.ec  (PMBEDDEDC) 
. / samedl . 1 ib/ E_2 . o  ( OBJECTFILE ) 


Diagnostics 

An  eiTor  is  reported  and  no  action  is  taken  if  tnod»de_nont£  does  not  exist  in  the  library,  or  if  the 
library  is  not  valid  or  is  locked. 
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8.6  sde.inkscript 
Command 

sde.inkscript  -  generate  an  Ada  compilation  script  file  for  an  interface  file 

Syntax 

sde.inkscript  [options]  module _rumie  ... 

Options 

-library  pathname  Operate  in  the  SDE  library  pathname.  If  not 

specified,  will  default  to  current  working 
directory 

•output  filename  Place  the  generated  script  template  into  filename 

Description 

sde.mkscript  wiU  create  a  template  for  performing  the  Ada  compilation  of  the  generated  Ada 
files  (and  the  units  they  depend  on)  for  the  definitional  or  abstract  module(s)  specified. 

Examples 

Suppose  in  the  library  /usr/bome/jdoe/my  lib  you  have  compiled  the  abstrart  module  my_abs 
which  depends  (WITHs)  the  schema  module  my_sch  and  the  definitional  module  myjdef; 
my_sch  depends  only  on  my  def  and  my_def  de^nds  on  no  modules.  Performing  an  ide.ls 
coifimand  gives  the  following  information:  ~ 

%sde.ls  -V  -a  -1  /usr/home/ jdoe/iny_lib  ny_abs  ny_def  niy_sch 

iry_abs 

Unit  Kind:  ABSMODULE 
Source  File:  input. sme 

Library  File:  /usr/home/ jdoe/iny_lib/8ainedl .  lib/A_l  .sme 
Time  Entered:  Feb  24  1992  11:59 
Interface  Files: 

/usr/home/ jdoe/my_lib/samedl . lib/P_2_.a  (ADASPEC) 

/usr/home/ jdoe/my_lib/saffledl . lib/B_2 .a  (ADABODY) 


my_def 

Unit  Kind:  DEFMODULE 
Source  File:  input .sme 

Library  File:  /usr /home/ jdoe/my_lib/s^unedl.lib/D_l. sme 
Time  Entered:  Feb  24  1992  11:59 
Interface  Files: 

/usr/h«M/ jdoe/iiiy_lib/seuBedl.lib/P_l_.a  (ADASPEC) 
/usr/home/ jdoe/my.lib/samedl . lib/B_l .a  (ADABODY) 
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ny_*ch 

Unit  Kind:  SCHEMAMODULE 
Sovirce  File:  input. sme 

Library  File:  /usr/hame/jdoe/iiy_lib/sainedl.lib/S_l.sne 
Tine  Entered:  Feb  24  1992  11:59 


You  may  issue  a  sde.inkscript  command  to  generate  an  Ada  compilation  template  for  compiling 
the  Ada  interface  files  associated  with  mynahs  as  follows: 

%sde  .mkscript  -1  /usr/h<Mne/jdoe/iEy_lib  -o  n^^script  iny_€d3s 
%more  my_script 

Compile  (Source  s>  */usr/same/exas^le/s2u&elib/sanedl.lib/P_l_.a*) ; 
Compile  (Source  =>  * /usr/same/exanple/seuDelib/samedl . lib/B_l .a* ) ; 

Ccanpile  (Source  s>  ''/usr/same/exaiiple/seuBelib/samedl.lib/P_2_.a* ) ; 
Compile  (Source  s>  ''/u8r/same/ex^unple/sanelib/s^uBedl.lib/B_2.a*)  ; 

Compile  (Source  =>  “/uer/seuDe/example/samelib/samedl  .lib/P_3_.a*  )  ; 
Compile  (Source  =>  * /usr/same/exanple/samelib/sanedl . lib/B_3 .a* ) ; 


Diagnostics 

An  error  is  reported  and  no  action  is  taken  if  module  name  is  not  an  abstract  or  defuiitional 
module  or  does  not  exist  in  the  library,  or  if  the  library  is  not  valid  tm  is  locked. 
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8.7  sde.purge 
Command 

sde.purge  -  remove  out  of  date/unused  files  from  an  SDE  library 

Syntax 

sde.purge  {pathname] 

Description 

sde.purge  will  empty  an  existing  SDE  library  of  all  obsolete  or  unused  files.  The  conunand  will 
remove  all  out  of  date  (due  to  recompilation  for  example)  ot  unused  files  (compiler  temporary 
fries  or  files  associated  with  modules  that  have  been  removed  via  sde.rm)  along  with  the  library 
state  backup  frle  samedLdatback  in  the  samedLlib  directory  from  the  associated  with 
pathname;  if  pathname  is  not  specified,  then  the  SDE  library  will  default  to  the  curet  working 
directory. 

Note  that,  because  sde.purge  removes  the  library  state  backup  frle  saiiiedl.dat.back,  an  SDE 
library  may  not  be  restored  back  to  its  prior  state  once  a  purge  is  ^rformed.  Normally,  library 
restoration  would  be  accomplished  by  renaming  the  sanMMll.dat.tack  file  to  samedLdat  in  the 
samedKlib  directory  for  the  library.  For  example: 

%cd  pa thname/samedl. lib 
%ls  samedl.dat* 

samedl . dat  samedl . dat . back 

%nn  samedl. dat 

%mv  samedl. dat. back  samedl.dat 


Examples 

The  following  sequence  of  commands  purges  the  library  contained  in  the  directory 
/bome/samedl. 

%cd  /home /samedl 
% sde.purge 


The  following  command  does  the  same  thing: 
%sde. purge  /hcnne/samedl 


Diagnostics 

An  error  is  reported  and  no  action  is  taken  if  pathname  does  not  specify  a  valid,  unlocked  SDE 
library. 
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8.8  sde.nii 
Command 

sde.nn  -  remove  a  SAMeDL  module  from  a  library 

Syntax 

sde.nn  [options]  module _name  ... 

Options 

•force  Suppress  the  confirmation  prompt  and  force 

deletion 

•library  pathname  Operate  in  the  SDE  library  pathname.  If  not 

specified,  will  default  to  current  working 
directory 


Description 

sde.nn  removes  all  information  and  related  interface  fries  associated  with  the  named  inodule(s). 

Unless  the  -force  option  is  specifred,  the  user  will  be  issued  a  confirmation  prompt  for  each 
module  to  be  removed.  The  user  may  respond  with  a  y  (or  Y)  if  the  nnodule  should  be  deleted; 
any  other  response  will  result  in  the  module  being  retained. 

Examples 

The  following  sequence  of  commands  removes  the  unit  abstract_mod  from  the  SDE  library 
present  in  the  directory  /home/samedl.  ~ 

ted  /home/samedl 
tsde.rro  abstract_inod 

sde.rm:  Delete  ABSMODULE  abstract_inod?  [N] :  y 

The  following  command  does  the  same  thing  but  eliminates  the  confirmation  pronqit: 
tsde.xm  -1  /home/samedl  -f  abstract_mod 


Diagnostics 

An  error  is  reported  and  no  action  is  taken  if  module jutme  does  not  exist  in  the  library,  or  if  tiie 
library  is  not  valid  or  is  lodmd. 
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8.9  sde.rmlib 
Command 

sde.niilib  •  remove  an  SDE  library 

Syntax 

sde.rmlib  [pathname] 

Description 

sde.rmlib  removes  all  information  in  the  SDE  library  in  the  directory  speciAed  by  pathname 
(the  current  directory  is  the  default).  It  deletes  all  the  files  in  the  SDE  library  directory 
samedLlib,  and  then  removes  the  directory. 

The  user  will  be  issued  a  confirmation  prompt  The  user  may  respond  with  a  y  (or  Y)  if  the 
library  should  be  deleted;  any  other  response  will  abort  the  conunand  and  retain  the  library 
unchanged. 

Examples 

The  following  sequence  of  commands  removes  the  SDE  library  present  in  the  directory 
/home/samedl. 

%cd  /home/samedl 
%8de.rmlib 

sde.rmlib:  Delete  ./samedl.lib?  (N] :  y 

The  following  command  does  the  same  thing: 

%sde.rmlib  /home/samedl 

sde.rmlib:  Delete  /home/samedl /samedl . lib?  [N] :  y 


Diagnostics 

An  error  is  reponed  and  no  action  is  taken  if  the  library  is  not  valid  or  is  locked. 
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